ATSUGetAllLineControls

OSStatus ATSUGetAllLineControls (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iLineStart,
                     ATSUAttributeInfo oAttributeInfoArray[],
                     ItemCount iTagValuePairArraySize,
                     ItemCount *oTagValuePairCount);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to a text layout object that contains the line whose attribute information you want to obtain. You cannot pass NULL for this parameter.

iLineStart

A value of type UniCharArrayOffset. Pass the edge offset in backing store memory that corresponds to the beginning of the line whose text layout attribute values you want to determine.

oAttributeInfoArray

An array of structures of type ATSUAttributeInfo. Before calling ATSUGetAllAttributes, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains the tag and data size pairs corresponding to all previously set text layout attribute values in the text layout object.

iTagValuePairArraySize

The maximum number of tag and data size pairs in the text layout object. Typically, this is equivalent to the number of ATSUAttributeInfo structures in the oAttributeInfoArray array. To determine this value, see the discussion below.

oTagValuePairCount

A pointer to a count. On return, the actual number of ATSUAttributeInfo structures in a line of the text layout object. This may be greater than the value you specified in the iTagValuePairArraySize parameter. You cannot pass NULL for this parameter.

DISCUSSION

The ATSUGetAllLineControls function obtains, for a line of text, an array of the tags and data sizes corresponding to all previously set text layout attribute values. You can obtain a particular attribute value by passing the corresponding tag and data size pair to the function ATSUGetLineControl. To obtain the tags and data sizes corresponding to all previously set text layout attribute values in an entire text layout object, call the function ATSUGetAllLayoutControls.

The best way to use ATSUGetAllLineControls is to call it twice:

Pass a reference to the text layout object containing the attribute in the iTextLayout parameter, NULL for the oAttributeInfoArray parameter, and 0 for the other parameters. ATSUGetAllLineControls returns the size of the oAttributeInfoArray array in the oTagValuePairCount parameter.
Allocate enough space for an array of the returned size, then call the function again, passing a pointer in the oAttributeInfoArray parameter; on return, the pointer references the oAttributeInfoArray array.

VERSION NOTES

Available beginning with ATSUI 1.1.